\chapter{CRE2常用类型与接口}\label{cre2-app-interface}

\section{数据类型}

在CRE2中定义了如下主要数据类型：

\begin{description}
  \item[\cinline{cre2_regexp_t}:]不透明正则表达式对象类型，用于声明正则表达式
      对象。该类型的对象可以用于任意数量的匹配操作，并可安全地供多线程并发使用。
  \item[\cinline{cre2_string_t}:]字符串切片数据结构。
      其 \cinline{const char * data} 字段用于指定切片起始位置，
      \cinline{int length} 字段用于指定切片长度。
  \item[\cinline{cre2_named_groups_iter_t}:]不透明类型，用于指定正则表达式分组的
      迭代器。
  \item[\cinline{cre2_error_code_t}:]错误代码枚举类型(由 \cinline{cre2_error_code()} %
      函数返回)，包含：
      \begin{itemize}
        \item \cinline{CRE2_NO_ERROR}: 值为0，表示操作成功
        \item \cinline{CRE2_ERROR_INTERNAL}: 未知错误
        \item \cinline{CRE2_ERROR_BAD_ESCAPE}: 转义字符错误
        \item \cinline{CRE2_ERROR_BAD_CHAR_CLASS}: 列表错误（class）
        \item \cinline{CRE2_ERROR_BAD_CHAR_RANGE}: 列表范围错误
        \item \cinline{CRE2_ERROR_MISSING_BRACKET}: 丢失\cinline{']'}符号
        \item \cinline{CRE2_ERROR_MISSING_PAREN}: 丢失\cinline{')'}符号
        \item \cinline{CRE2_ERROR_TRAILING_BACKSLASH}: 在正则表达式末尾存在\verb|'\'|
        \item \cinline{CRE2_ERROR_REPEAT_ARGUMENT}: 缺少重复参数，例如\cinline{'*'}
        \item \cinline{CRE2_ERROR_REPEAT_SIZE}: 重复参数错误
        \item \cinline{CRE2_ERROR_REPEAT_OP}: 重复运算符错误
        \item \cinline{CRE2_ERROR_BAD_PERL_OP}: Perl运算符错误
        \item \cinline{CRE2_ERROR_BAD_UTF8}: 在正则表达式中存在无效UTF-8字符
        \item \cinline{CRE2_ERROR_BAD_NAMED_CAPTURE}: 命名捕获分组错误
        \item \cinline{CRE2_ERROR_PATTERN_TOO_LARGE}: 模式过大，编译失败
      \end{itemize}
  \item[\cinline{cre2_options_t}:] 不透明数据类型，该类型的任何实例都可以用于
      配置任意数量的正则表达式对象。
  \item[\cinline{cre2_encoding_t}:] 用于选择字符编码方式的枚举常量，包含如下符号：
      \begin{itemize}
        \item \cinline{CRE2_UNKNOWN}: 不应该使用该值，它仅用于区分RE2和CRE2引擎。
        \item \cinline{CRE2_UTF8}: UTF8编码，默认值。
        \item \cinline{CRE2_Latin1}: Latin1（ISO-88596-1）编码。
      \end{itemize}
  \item[\cinline{cre2_anchor_t}:] 匹配操作锚点枚举常量，包含：
      \begin{itemize}
        \item \cinline{CRE2_UNANCHORED}: 不使用锚点
        \item \cinline{CRE2_ANCHOR_START}: 使用起始锚点
        \item \cinline{CRE2_ANCHOR_BOTH}: 使用起始和结束锚点
      \end{itemize}
  \item[\cinline{cre2_range_t}:] 用于表示起始和结束的子字符串。
      有如下字段：
      \begin{itemize}
        \item \cinline{long start}: 起始字符索引值（含该字符）
        \item \cinline{long past}: 结束字符索引值（不含该字符）
      \end{itemize}
  \item[\cinline{cre2_set}:] 不透明数据类型，用于声明模式集合。
\end{description}

\section{用户接口}
在CRE2中定义了如下用户接口函数：
\begin{description}
  \item[\cinline{cre2_new()}:] 模式构造函数
  \item[\cinline{cre2_delete()}:] 模式析构函数（删除）
  \item[\cinline{cre2_pattern()}:] 返回模式字符串指针
  \item[\cinline{cre2_program_size()}:] 返回模式对象大小（非负整数），
      如果模式对象构造失败，则返回-1。这是衡量正则表达式\enquote{成本}%
      的一个近似指标，数字越大，表示成本越高。
  \item[\cinline{cre2_num_capturing_groups()}:] 返回表示模式中分组数量(小括号
      子表达式)的非负整数。如果模式构建错误，则返回-1。
  \item[\cinline{cre2_find_named_capturing_groups()}:] 返回指定的命名分组的
      索引号(非负整数)。如果模式构建出错或名称无效，则返回-1。
  \item[\cinline{cre2_named_groups_iter_new()}:] 构建并返回一个新的已命名捕获分组迭代器。
  \item[\cinline{cre2_named_groups_iter_delete()}:] 删除一个已命名的捕获分组迭代器。
  \item[\cinline{cre2_named_groups_iter_next()}:] 搜索下一个命名的捕获分组迭代器。
      如果发现分组则返回\cinline{true}，如果未找到，则返回\cinline{false}。
  \item[\cinline{cre2_error_code()}:] 如果构建模式时发生错误，则返回错误码，
      否则返回0。
  \item[\cinline{cre2_error_string()}:] 返回错误信息(模式不能被删除)。
  \item[\cinline{cre2_error_arg()}:] 返回正则表达式的错误内容。
  \item[\cinline{cre2_opt_new()}:] 构建一个新的选项对象，如果内存分配出错，则返回
      \cinline{NULL}。
  \item[\cinline{cre2_opt_delete()}:] 释放选项对象占有的资源，但不影响通过该对象
      编译的正则表达式。
  \item[\cinline{cre2_opt_encoding()}:] 返回字符编码。
  \item[\cinline{cre2_opt_set_encoding()}:] 设置字符编码，默认情况下采用UTF-8编码。
  \item[\cinline{cre2_opt_posix_syntax()}:] 返回POSIX EGREP语法状态。
  \item[\cinline{cre2_opt_set_posix_syntax()}:] 设置POSIX EGREP语法状态，默认为关闭。
  \item[\cinline{cre2_opt_longest_match()}:] 返回最长匹配状态。
  \item[\cinline{cre2_opt_set_longest_match()}:] 设置最长匹配状态，默认为禁用。
  \item[\cinline{cre2_opt_log_errors()}:] 返回语法日志及执行错误输出状态。
  \item[\cinline{cre2_opt_set_log_errors()}:] 设置是否将语法日志及执行错误输出到%
      \cinline{stderr}，默认为禁用。
  \item[\cinline{cre2_opt_literal()}:] 返回模式是否为字面量状态。
  \item[\cinline{cre2_opt_set_literal()}:] 设置模式是否为字面量，默认为禁止。
  \item[\cinline{cre2_opt_never_nl()}:] 返回是否匹配\cinline{'\n'}字符的状态。
  \item[\cinline{cre2_opt_set_never_nl()}:] 设置是否匹配\cinline{'\n'}字符，默认为禁止。
  \item[\cinline{cre2_opt_dot_nl()}:] 返回\cinline{'.'}是否匹配包括\cinline{'\n'}的所有
      字符的状态。
  \item[\cinline{cre2_opt_set_dot_nl()}:] 设置\cinline{'.'}匹配状态，默认为禁用。
  \item[\cinline{cre2_opt_never_capture()}:] 返回不捕获所有括号的状态。
  \item[\cinline{cre2_opt_set_never_capture()}:] 设置不捕获所有括号的状态，默认为禁用。
  \item[\cinline{cre2_opt_case_sensitive()}:] 返回是否忽略大小写的状态。
  \item[\cinline{cre2_opt_set_case_sensitive()}:] 设置是否忽略大小写，除非设置了POSIX
      语法，否则正则表达式中的\cinline{?i}可以覆盖此设置，默认为区分大小写。
  \item[\cinline{cre2_opt_max_mem()}:] 返回编译正则表达式及其DFA图的缓存的最大内存容量。
  \item[\cinline{cre2_opt_set_max_mem()}:] 设置编译正则表达式及其DFA图的缓存的最大内存容量。
  \item[\cinline{cre2_opt_perl_classes()}:] 返回是否允许Perl语法状态。
  \item[\cinline{cre2_opt_set_perl_classes()}:] 设置是否允许使用Perl的
      \cinline{'\d'}, \cinline{'\s'}, \cinline{'\w'}, \cinline{'\D'},
      \cinline{'\S'}, \cinline{'\W'}。默认为禁用。
  \item[\cinline{cre2_opt_word_boundary()}:] 返回是否允许Perl语法状态。
  \item[\cinline{cre2_opt_set_word_boundary()}:] 设置是否允许使用Perl的
      \cinline{'\b'}, \cinline{'\B'}。默认为禁用。
  \item[\cinline{cre2_opt_one_line()}:] 返回\cinline{'^'}和\cinline{'$'}的使用状态。
  \item[\cinline{cre2_opt_set_one_line()}:] 设置\cinline{'^'}和\cinline{'$'}
      是否匹配文本的开始和结束状态，默认为禁用。
  \item[\cinline{cre2_match()}:] 用编译后的正则表达式进行匹配。如果匹配成功，
      则返回\cinline{true}，否则返回\cinline{false}。
  \item[\cinline{cre2_easy_match()}:] 直接用正则表达式进行匹配，并且
      执行完全匹配，不使用锚点。如果匹配成功，则返回1，如果不匹配，则返回0，
      如果模式无效，则返回2。
  \item[\cinline{cre2_strings_to_ranges()}:] 提取指定范围的子字符串。
  \item[\cinline{cre2_full_match()}:] 直接与正则表达式进行完整匹配。
  \item[\cinline{cre2_full_match_re()}:] 与编译后的正则表达式进行完整匹配。
  \item[\cinline{cre2_partial_match()}:] 直接与正则表达式进行部分匹配。
  \item[\cinline{cre2_partial_match_re()}:] 与编译后的正则表达式进行部分匹配。
  \item[\cinline{cre2_consume()}:] 直接与正则表达式进行剔除匹配，匹配后，字符串
      指针会指向匹配的最后一个字符后的字符。
  \item[\cinline{cre2_consume_re()}:] 与编译后的正则表达式剔除匹配，匹配后，字符串
      指针会指向匹配的最后一个字符后的字符。
  \item[\cinline{cre2_find_and_consume()}:] 直接与正则表达式查找并剔除匹配，匹配后，字符串
      指针会指向匹配的最后一个字符后的字符。
  \item[\cinline{cre2_find_and_consume_re()}:] 与编译后的正则表达式进行查找并剔除匹配，匹配后，字符串
      指针会指向匹配的最后一个字符后的字符。
  \item[\cinline{cre2_replace()}:] 直接用正则表达式替换第一个匹配项。
  \item[\cinline{cre2_replace_re()}:] 用编译后的正则表达式替换第一个匹配项。
  \item[\cinline{cre2_global_replace()}:] 直接用正则表达式全局替换所有匹配项。
  \item[\cinline{cre2_global_replace_re()}:] 用编译后的正则表达式全局替换所有匹配项。
  \item[\cinline{cre2_extract()}:] 直接用正则表达式提取匹配项并对其进行替换。
  \item[\cinline{cre2_extract_re()}:] 用编译后的正则表达式提取匹配项并对其进行替换。
  \item[\cinline{cre2_set_new()}:] 创建正则表达式集合对象。
  \item[\cinline{cre2_set_delete()}:] 删除正则表达式集合对象。
  \item[\cinline{cre2_set_add()}:] 为模式集合添加正则表达式。
  \item[\cinline{cre2_set_add_simple()}:] 直接为正则表达式集合添加模式。
  \item[\cinline{cre2_set_compile()}:] 编译正则表达式集合。
  \item[\cinline{cre2_set_match()}:] 执行正则表达式集合匹配，返回选用的正则表达式个数。
  \item[\cinline{cre2_quote_meta()}:] 由单反斜杠引出元字符正则表达式创建模式。
  \item[\cinline{cre2_possible_match_range()}:] 计算最短和最长匹配。
  \item[\cinline{cre2_check_rewrite_string()}:] 检查替换字符串是否适用于当前正则表达式。
  \item[\cinline{cre2_version_string()}:] 返回版本字符串。
  \item[\cinline{cre2_version_interface_current()}:] 返回当前库接口版本号。
  \item[\cinline{cre2_version_interface_revision()}:] 返回当前库接口的修订号
  \item[\cinline{cre2_version_interface_age()}:] 返回 当前库接口时间。
\end{description}
